Add some docs about JSON messages

diff --git a/src/doc/header.html b/src/doc/header.html
index 2ab3c4b42731b9674f04b673dd6a636553054f6f..83e76173c95a38a1c092b95fc880644d5039a5b5 100644 (file)
--- a/src/doc/header.html
+++ b/src/doc/header.html
@@ -39,6 +39,7 @@
                 <li><a href='pkgid-spec.html'>Package ID specs</a></li>
                 <li><a href='environment-variables.html'>Environment Variables</a></li>
                 <li><a href='source-replacement.html'>Source Replacement</a></li>
+                <li><a href='machine-readable-output.html'>Machine readable output</a></li>
                 <li><a href='policies.html'>Policies</a></li>
             </ul>
         </div>

diff --git a/src/doc/machine-readable-output.md b/src/doc/machine-readable-output.md
new file mode 100644 (file)
index 0000000..e486fd6
--- /dev/null
+++ b/src/doc/machine-readable-output.md
@@ -0,0 +1,78 @@
+% Machine readable output.
+
+Cargo can output information about project and build in JSON format.
+
+# Information about project structure
+
+You can use `cargo metadata` command to get information about project structure
+and dependencies. The output of the command looks like this:
+
+```
+{
+  // Integer version number of the format.
+  "version": integer,
+
+  // List of packages for this workspace, including dependencies.
+  "packages": [
+    {
+      // Opaque package identifier.
+      "id": PackageId,
+
+      "name": string,
+
+      "version": string,
+
+      "source": SourceId,
+
+      // A list of declared dependencies, see `resolve` field for actual dependencies.
+      "dependencies": [ Dependency ],
+
+      "targets: [ Target ],
+
+      // Path to Cargo.toml
+      "manifest_path": string,
+    }
+  ],
+
+  "workspace_members": [ PackageId ],
+
+  // Dependencies graph.
+  "resolve": {
+     "nodes": [
+       {
+         "id": PackageId,
+         "dependencies": [ PackageId ]
+       }
+     ]
+  }
+}
+```
+
+
+# Compiler errors
+
+If you supply `--message-format json` to commands like `cargo build`, Cargo
+reports compilation errors and warnings in JSON format. Messages go to the
+standard output. Each message occupies exactly one line and does not contain
+internal `\n` symbols, so it is possible to process messages one by one
+without waiting for the whole build to finish.
+
+The message format looks like this:
+
+```
+{
+  // Type of the message.
+  "reason": "compiler-message",
+
+  // Unique opaque identifier of compiled package.
+  "package_id": PackageId,
+
+  // Unique specification of a particular target within the package.
+  "target": Target,
+
+  // The error message from the compiler in JSON format.
+  "message": {...}
+}
+```
+
+Package and target specification are the same that `cargo metadata` uses.